استخدام Passport لإعداد خادوم OAuth على Laravel: دليل شامل وموسع

في عصر التحول الرقمي المتسارع وتزايد الحاجة إلى تطبيقات الويب والخدمات المتعددة التي تتطلب مستويات متقدمة من الأمان والتوثيق، أصبح من الضروري توفير حلول قوية لإدارة الهوية والتفويض بين التطبيقات. من أبرز هذه الحلول في بيئة PHP هو استخدام OAuth 2.0 كبروتوكول تفويض، وLaravel Passport كأداة متكاملة لإعداد خادوم OAuth داخل إطار عمل Laravel.

هذا المقال يهدف إلى تقديم شرح معمق ومفصل لكيفية إعداد واستخدام Laravel Passport لخادوم OAuth 2.0، مع توضيح المفاهيم الأساسية، خطوات التنفيذ، وأفضل الممارسات لضمان بناء نظام تفويض متين وفعال.

مقدمة عن OAuth و Laravel Passport

ما هو OAuth 2.0؟

OAuth 2.0 هو بروتوكول تفويض يُستخدم للسماح لتطبيق ما بالوصول إلى موارد محمية في تطبيق آخر نيابةً عن المستخدم، دون الحاجة إلى مشاركة بيانات اعتماد المستخدم مثل كلمة المرور. يستخدم OAuth رموز وصول (Access Tokens) تمنح الصلاحيات اللازمة للتطبيق للوصول إلى الموارد المطلوبة ضمن نطاق محدد.

لماذا نستخدم Laravel Passport؟

Laravel Passport هو مكتبة رسمية من Laravel توفر حلاً متكاملاً لإضافة دعم OAuth 2.0 في تطبيقات Laravel بسهولة، مما يجعل عملية إنشاء خادوم تفويض آمنة وبسيطة. Passport يستند إلى مكتبة League OAuth2 Server الشهيرة، ويأتي معه مجموعة من الأدوات المساعدة، مثل إدارة رموز الوصول، إدارة عملاء OAuth، إنشاء توكنات الوصول، وتجديدها بسهولة.

المفاهيم الأساسية في OAuth 2.0

قبل الدخول في تفاصيل إعداد Passport، من المهم فهم المفاهيم الأساسية التي يعتمد عليها OAuth 2.0:

• Resource Owner (مالك المورد): المستخدم الذي يمتلك البيانات التي يحتاج التطبيق الوصول إليها.

• Client (العميل): التطبيق الذي يريد الوصول إلى موارد المستخدم.

• Authorization Server (خادوم التفويض): الخادم الذي يصدر رموز الوصول بعد التحقق من هوية المستخدم.

• Resource Server (خادوم الموارد): الخادم الذي يحمي الموارد ويمنح الوصول إليها بناءً على رموز الوصول.

• Access Token (رمز الوصول): رمز مؤقت يسمح بالوصول إلى الموارد المحمية ضمن صلاحيات محددة.

الخطوات العملية لإعداد Laravel Passport على Laravel

1. متطلبات النظام

• Laravel 8 أو أحدث.

• PHP 7.4 أو أحدث.

• Composer مثبت على بيئة التطوير.

• قاعدة بيانات مهيأة (MySQL، PostgreSQL، SQLite، وغيرها).

2. تثبيت Laravel Passport

يتم تثبيت Passport عبر Composer بالأمر التالي:

bash
CopyEdit
composer require laravel/passport

بعد التثبيت، تحتاج إلى تنفيذ خطوات التهيئة التي تتيح دمج Passport مع التطبيق.

3. إعداد Passport في التطبيق

أ. تسجيل Service Provider

في إصدارات Laravel الحديثة (8 وأعلى)، لا تحتاج إلى تسجيل Service Provider يدوياً، إذ يتم ذلك تلقائياً عبر Auto-Discovery. لكن في حال استخدام إصدار أقدم، يمكن إضافة الكود التالي في ملف config/app.php ضمن المصفوفة providers:

php
CopyEdit
Laravel\Passport\PassportServiceProvider::class,

ب. تشغيل المهاجرات (Migrations)

Passport يتطلب مجموعة من الجداول لإدارة عملاء OAuth، رموز الوصول، وتجديدها. قم بتشغيل المهاجرات باستخدام:

bash
CopyEdit
php artisan migrate

ج. تثبيت ملفات Passport

لإنشاء المفاتيح الخاصة بـ Passport (Private/Public keys) لتوقيع رموز الوصول:

bash
CopyEdit
php artisan passport:install

الأمر أعلاه يولد مفاتيح التشفير ويُنشئ عملاء OAuth الافتراضيين.

4. تكامل Passport مع نظام التوثيق في Laravel

أ. تفعيل استخدام Passport في نموذج المستخدم

في نموذج المستخدم User.php يجب استخدام trait خاص بـ Passport:

php
CopyEdit
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    // بقية تعريف النموذج...
}

ب. تعديل إعدادات Auth Config

في ملف config/auth.php، تحتاج لتغيير قيمة driver الخاصة بـ api إلى passport:

php
CopyEdit
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],

    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

هذا يربط نظام التوثيق بـ Passport ليستخدم رموز OAuth في حماية الـ API.

5. إعداد مسارات Passport في تطبيق Laravel

في ملف app/Providers/AuthServiceProvider.php، قم بإضافة السطر التالي داخل دالة boot():

php
CopyEdit
use Laravel\Passport\Passport;

public function boot()
{
    $this->registerPolicies();

    Passport::routes();
}

هذا السطر يقوم بتسجيل مسارات Passport الخاصة بإنشاء رموز الوصول، تجديدها، وإدارة العملاء.

6. أنواع عملاء OAuth في Passport

Passport يدعم عدة أنواع من عملاء OAuth، لكل نوع سيناريو استخدام معين:

• Client Credentials: يستخدم للتطبيقات التي لا تتطلب تفويض المستخدم (خدمات خلفية).

• Password Grant: يستخدم لتطبيقات الويب أو الموبايل التي تحتاج اسم المستخدم وكلمة المرور.

• Authorization Code Grant: يستخدم لتطبيقات الويب التي تعمل على المتصفح (باستخدام إعادة التوجيه).

• Personal Access Tokens: رموز وصول خاصة تستخدم للوصول السريع بدون تعقيدات OAuth الكاملة (غالباً لاختبارات المطورين).

7. كيفية إنشاء عميل OAuth جديد

يمكن إنشاء عميل جديد باستخدام الأمر:

bash
CopyEdit
php artisan passport:client

سيُطلب منك اختيار نوع العميل (مثل client credentials أو authorization code). بعد الإنشاء، سيتم توفير Client ID و Client Secret للاستخدام في طلبات OAuth.

8. بناء نظام التفويض عبر Passport

أ. طريقة إصدار رمز الوصول باستخدام Password Grant

يمكن إرسال طلب POST إلى نقطة النهاية /oauth/token مع بيانات الاعتماد التالية:

• grant_type: “password”

• client_id: رقم العميل

• client_secret: السر الخاص بالعميل

• username: البريد الإلكتروني أو اسم المستخدم

• password: كلمة المرور

• scope: نطاق الوصول (اختياري)

يتم الرد برمز وصول (access_token) يُستخدم لاحقاً في كل طلب إلى API عبر هيدر Authorization: Bearer {access_token}.

ب. تجديد رموز الوصول (Refresh Tokens)

يمكن إرسال طلب مشابه مع grant_type يعادل “refresh_token” مع تقديم رمز التجديد (refresh_token) لتجديد صلاحية الوصول بدون إعادة تسجيل دخول المستخدم.

9. حماية مسارات API باستخدام Middleware

لتأمين مسارات الـ API يجب استخدام Middleware auth:api في ملف تعريف المسارات routes/api.php:

php
CopyEdit
Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

هذا يضمن أن كل طلب إلى هذا المسار يحتاج إلى رمز وصول OAuth صالح.

10. تخصيص إعدادات Passport

يمكن تخصيص عدة جوانب في Passport حسب الحاجة، مثل:

• تغيير مدة صلاحية Access Token و Refresh Token:

php
CopyEdit
use Laravel\Passport\Passport;
use Carbon\Carbon;

public function boot()
{
    Passport::routes();

    Passport::tokensExpireIn(Carbon::now()->addMinutes(60));
    Passport::refreshTokensExpireIn(Carbon::now()->addDays(30));
}

• إدارة Scopes (نطاقات الوصول):

يمكن تحديد Scopes لتقييد صلاحيات التوكنات، مثال:

php
CopyEdit
Passport::tokensCan([
    'check-status' => 'Check order status',
    'place-orders' => 'Place new orders',
]);

وعند إصدار الرمز يمكن طلب نطاق معين.

11. التعامل مع OAuth في واجهات المستخدم الخارجية

يستطيع المطورون بناء تطبيقات خارجية (مثل تطبيقات الجوال أو مواقع ويب أخرى) باستخدام Client ID و Client Secret لإجراء عمليات OAuth، حيث يتم تنفيذ سير التفويض من خلال إعادة التوجيه أو تبادل بيانات الاعتماد حسب نوع العميل.

12. مميزات Laravel Passport

• تكامل كامل مع Laravel: يتماشى Passport بسلاسة مع بنية Laravel وأنظمة التوثيق.

• إدارة تلقائية للمفاتيح: إنشاء المفاتيح الخاصة والعامة والتوقيع.

• واجهة API واضحة: مسارات API جاهزة للاستخدام مع دعم تجديد الرموز.

• دعم Scopes: تحديد صلاحيات مفصلة للتوكنات.

• تجديد تلقائي للرموز: دعم رموز التجديد لتوفير تجربة مستخدم سلسة.

• أمان عالٍ: يعتمد على مكتبة OAuth2 Server الشهيرة.

13. مقارنة بين Passport و Sanctum

بينما يوفر Passport نظام OAuth2 كامل مع دعم رموز الوصول، يستخدم Laravel Sanctum عادةً لآليات توثيق أخف، مثل توكنات API الشخصية والاعتماد عبر الجلسات. Passport مفضل في التطبيقات التي تحتاج إلى دعم OAuth2 كامل مثل تفويض الطرف الثالث، أما Sanctum فيفضل للتطبيقات البسيطة أو SPA.

جدول مقارنة بين أنواع عملاء OAuth في Passport

نصائح أمنية عند استخدام Passport

• يجب تأمين Client Secret وعدم مشاركته في واجهات المستخدم.

• استخدم HTTPS دائمًا لتشفير البيانات أثناء النقل.

• حدد نطاقات (Scopes) دقيقة لتقليل صلاحيات التوكنات.

• راقب صلاحية رموز الوصول وراجع عمليات التجديد بشكل دوري.

• استخدم Middleware للتحقق من الصلاحيات قبل منح الوصول إلى الموارد.

• قم بتحديث مفاتيح التشفير دورياً لتقليل المخاطر الأمنية.

خاتمة

إن إعداد خادوم OAuth باستخدام Laravel Passport يمنح المطورين قدرة قوية ومرنة لإدارة التفويض والتوثيق بطريقة احترافية وآمنة. يوفر Passport بنية متكاملة مبنية على OAuth 2.0، تسمح لبناء أنظمة متطورة تشمل الوصول الآمن إلى الموارد، دعم التطبيقات المتعددة، وإدارة الصلاحيات بكفاءة عالية.

من خلال اتباع الخطوات التفصيلية المذكورة، يمكن لأي مطور Laravel إنشاء نظام تفويض متين يدعم مختلف السيناريوهات سواء لتطبيقات الويب، الهواتف الذكية، أو الخدمات الخلفية، مع الالتزام بأفضل ممارسات الأمان وحماية بيانات المستخدم.

المصادر والمراجع

• Laravel Passport Documentation

• OAuth 2.0 Framework – RFC 6749